home *** CD-ROM | disk | FTP | other *** search
/ The Very Best of Atari Inside / The Very Best of Atari Inside 1.iso / mint / mintmant / psemapho.txt < prev    next >
Text File  |  1992-03-24  |  4KB  |  130 lines
  1. Psemaphore(2)             Jan. 6, 1992              Psemaphore(2)
  2.  
  3.  
  4.  
  5. NAME
  6.      Psemaphore - create / use / destroy a sempahore
  7.  
  8. SYNOPSIS
  9.      LONG Psemaphore( WORD mode, LONG id, long timeout )
  10.  
  11. DESCRIPTION
  12.      Psemaphore is a call that implements uncounted semaphores. A
  13.      semaphore  is used for mutual exclusion: only one process at
  14.      a time may "own" a given semaphore.
  15.  
  16.      For example, a semaphore may be used to  protect  access  to
  17.      data  structures  which  are  in shared memory and which are
  18.      used by multiple threads in  a  process:  before  using  the
  19.      memory  a  thread  must gain ownership of the guarding sema-
  20.      phore, and when finished the thread must release  the  sema-
  21.      phore.  The semaphore would be created during initialization
  22.      and destroyed during shutdown.
  23.  
  24.      Semaphores are identified by an id, which  is  an  arbitrary
  25.      longword.   This  is  the semaphore's "name." The id used to
  26.      create the semaphore is the "name" of  that  semaphore  from
  27.      then  on.  When using semaphores, you should strive to use a
  28.      longword that is unique. Using four ASCII  characters  which
  29.      spell  out  something  is  common:  0x4b4f444f  ("MODM") for
  30.      instance might be the id of a semaphore that controls access
  31.      to  a  modem.  (Actually, this would be a poor choice, since
  32.      there can be more than one modem in a system and this  sema-
  33.      phore ID isn't flexible enough to handle that.  "MDM1" might
  34.      be better.)
  35.  
  36.      Semaphore id's beginning with 0x5f (the  underscore  charac-
  37.      ter) are reserved for operating system use.
  38.  
  39.      The timeout argument is only used in Mode 2. It  is  ignored
  40.      in  other  modes.  A  timeout  of zero means "return immedi-
  41.      ately."  A value of -1 means "forever" - that is, never time
  42.      out.  Other  values are a number of milliseconds to wait for
  43.      the semaphore before timing out.
  44.  
  45.      The mode argument is used to tell what operation the  caller
  46.      desires:
  47.  
  48.      MODE ACTION
  49.  
  50.      0    Create and "get" a semaphore with the given ID.
  51.  
  52.      1    Destroy the indicated semaphore. The  caller  must  own
  53.           the semaphore prior to making this call.
  54.  
  55.      2    Request ownership of the semaphore.  Blocks  until  the
  56.           semaphore  is  free  or  until the timeout expires. See
  57.  
  58.  
  59.  
  60. Version 0.92  Last change: MiNT Programmer's Manual             1
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67. Psemaphore(2)             Jan. 6, 1992              Psemaphore(2)
  68.  
  69.  
  70.  
  71.           below.
  72.  
  73.      3    Release the semaphore. The caller must  own  the  sema-
  74.           phore prior to making this call.
  75.  
  76. RETURNS
  77.      CODE MEANING
  78.  
  79.      0    Success.
  80.  
  81.      ERROR
  82.           A request for a  semaphore  which  the  caller  already
  83.           owns.
  84.  
  85.      ERANGE
  86.           The semaphore does not exist.
  87.  
  88.      EACCDN
  89.           Failure. The semaphore already  exists  (mode  0),  you
  90.           don't  own it (modes 1 and 3), or the request timed out
  91.           (mode 2).
  92.  
  93.  
  94. NOTES
  95.      When you create a semaphore you also own  it,  so  you  must
  96.      release  it  before  anybody  else  can  get  it. If you are
  97.      blocked waiting for a semaphore (mode 2 before  the  timeout
  98.      expires)  and somebody destroys the semaphore, the call will
  99.      return ERANGE to you (because the requested  semaphore  does
  100.      not exist any more!).
  101.  
  102.      When a  process  terminates,  any  semaphores  it  owns  are
  103.      released.
  104.  
  105.      At most one process may own a semaphore.  Ownership  is  not
  106.      inherited by children (fork()) or across exec().
  107.  
  108.      Once created, semaphores are  never  destroyed  except  upon
  109.      request.  Thus  if  a  program  creates a semaphore and then
  110.      crashes the semaphore will never go away.
  111.  
  112.      Semaphores can be implemented using  named  pipes  and  file
  113.      locking.  Technically,  then, semaphores are redundant.  The
  114.      facility is included as a kernel call because it was  deemed
  115.      necessary to have this kind of exclusion available with lit-
  116.      tle persistent state or system-call overhead.
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126. Version 0.92  Last change: MiNT Programmer's Manual             2
  127.  
  128.  
  129.  
  130.